User management¶

System Role: Administrator¶

The Administrator role implicitly has all system privileges. This also applies automatically when extensions are installed that expand the set of privileges. No privileges can be explicitly assigned to the Administrator role.

The administrator role can be assigned to any number of users. These admin users can be identified in the user overview by the label Admin next to their names.

Edit Admin Users¶

For security reasons, write access in user management is not sufficient for managing admin users. Administrator access is required for the following actions:

• Rename Admin User

• Delete Admin User

• Revoke the Admin role from an admin user

• Assign the admin role to a user

Before performing any action that reduces the number of users with admin roles, the system checks whether at least one active user with an admin role will remain in the system after the action. If this check returns a negative result, the action cannot be executed.

The following actions are affected:

• Deactivate Admin User

• Delete Admin User

• Revoke the Admin role from an admin user

Add user¶

1. Name: Unique name of a user. Specified when the user is created and displayed in overviews. Can be changed or anonymized later. The following characters are allowed:

   • Capital letters [A-Z]

   • Lowercase letters [a-z]

   • Digits [0-9]

   • Underscore _

   • Hyphen -

   • Maximum length: 64 characters

2. Password: Initial password for the user. The password must comply with the parameters of the password policy that has been set. When logging in for the first time, the user will be prompted to assign their own password before they can use the system.

3. Repeat password: Repeat the password to ensure that it does not contain any errors.

4. Roles: Using the dropdown menu, one or more roles can be assigned to a user directly during creation. Role assignment is optional and can alternatively be done later by editing the user or the corresponding roles.

Add role¶

1. Tab Name & permissions: The dialog has two tabs. In the first tab, the role name and the associated permissions can be assigned.

2. Name: Unique name of the role. Mandatory field. Displayed in overviews. Can be changed later.

3. Permissions: List of the system permissions, grouped by category. Permissions can be added to or removed from this role using the checkboxes. All Permissions selects or deselects all permissions at once. No selection is possible for the Administrator role, as it has all permissions by default.

1. Tab Assigned users: In the second tab, users can be assigned directly to a role while editing it. Alternatively, roles can be assigned via the users.

2. Users: List of users of the system. Users can be added or removed from this role by selecting or deselecting the checkboxes.

User management permissions¶

User management provides three permissions: User management: read access, User management: write access and User management: administrate access. No permission is required to set or change your own password. If the permission for a function is missing, the corresponding entry point is disabled and marked with the hint Missing permission. The following list shows the scope of functions covered by each permission.

Read access

• View user management and subpages in the navigation.

• Access user management pages and display data.

Write access

• Add, edit, and delete users. Restriction: Set passwords for other users.

• Add, edit, and delete roles. This also includes assigning permissions and users to roles.

• Add, edit and delete Clients.

• Edit the LDAP configuration.

• If admin users are affected, administrative privileges are always required.

Administrative access

• Set passwords for other users.

• End active sessions of users.

• Deactivate users so that they can no longer log in to the system, and activate them again.

• Edit User settings.

• Rename, deactivate, or delete an admin user.

• Remove the admin role from admin users.

• Assign the admin role to users.

Add client¶

1. Name: Name of the client. Mandatory field. 1 to 63 characters from lowercase letters [a-z], digits [0-9] and underscore _ are allowed. The name must start with a letter and must not end with an underscore. The name must not match the name of a user.

2. Permissions: List of the system permissions, grouped by category. All Permissions selects or deselects all permissions at once. At least one permission must be selected. The client can only request the permissions selected here.

The Save button is only enabled once at least one permission is selected. If the name does not meet the requirements, the client is not created and an error message is displayed.

After saving, the dialog shows the Client id and the Client secret of the new client. The copy icon copies the values to the clipboard, the eye icon reveals the client secret. OK closes the dialog.

Edit client¶

Edit in the menu opens the Edit client dialog. It corresponds to the dialog for adding and is prefilled with the name and permissions of the client. The client ID and client secret remain unchanged when editing.

Changed permissions apply to newly requested access tokens.

Delete client¶

Delete in the menu removes a client after confirmation in the Delete client dialog. Afterwards, no access token can be requested with its client ID and client secret.

Access tokens that have already been issued remain valid until they expire, i.e. for at most 5 minutes. To end access immediately, also delete the client’s sessions under Sessions.

Requesting access tokens for clients¶

The access token is requested via HTTP POST at the token endpoint of the system:

• Token endpoint: <base URL>/oauth/token. The base URL is the address at which the system is opened in the browser. The exact address of the token endpoint is provided by <base URL>/.well-known/openid-configuration in the field token_endpoint.

• Authentication: client ID and client secret via HTTP Basic Authentication.

• Parameter grant_type=client_credentials.

• Parameter scope: The required permissions as scopes, multiple scopes separated by spaces. Only scopes assigned to the client may be requested. Otherwise, the request is rejected. Without the scope parameter, the token receives no permissions.

Example with curl:

curl -u "<client_id>:<client_secret>" \
     -d "grant_type=client_credentials" \
     -d "scope=user-management:read" \
     <base_url>/oauth/token

The response contains the access token in the field access_token. In requests to the interfaces of the system, it is sent in the HTTP header Authorization: Bearer <access_token>.

The access token is valid for 5 minutes. No refresh token is issued; after expiry, a new access token is requested with the client ID and client secret. If a logout after inactivity is configured under Session settings, it also applies to access tokens of clients.

Issued access tokens are displayed under Sessions with the name of the client as username.

Permission scopes¶

The following table shows the scopes of the user management permissions. The target system and installed extensions provide further permissions with their own scopes. These are described in the documentation of the respective target system.

Password policies¶

The dialog box allows you to customize the password policy for the system globally. The default password policy is based on the recommendations of the German Federal Office for Information Security and provides the following parameters:

• Username must not be included in password

• Minimum length 8 characters

• At least 1 digit [0-9]

• At least 1 lowercase letter [a-z]

• At least 1 uppercase letter [A-Z]

• At least 1 special character

1. Password must not contain username: The mechanism checks whether the username is part of the password.

2. Minimum password length: The mechanism checks the number of characters contained in the password. Only the total number is considered, not the type of characters.

3. Minimum lowercase letters: The mechanism checks the number of lowercase letters contained in the password. This includes [a-z].

4. Minimum uppercase letters: The mechanism checks the number of uppercase letters contained in the password. This includes [A-Z].

5. Minimum digits: The mechanism checks the number of digits contained in the password. This includes [0-9].

6. Minimum special characters: The mechanism checks the number of special characters contained in the password. A special character is anything that is neither a letter nor a digit.

Session settings¶

The dialog box allows you to customize the session settings for the system globally. The default setting does not provide for automatic logout.

1. Logout after inactivity in minutes: After n minutes of inactivity, sessions are terminated automatically. The value 0 means no limit. Some functions use so-called long polling, which means that inactivity cannot be detected. Consequently, depending on how the system is used, a logout after the time span has elapsed cannot currently be guaranteed.

Login policies¶

The dialog box allows you to customize the login policy for the system globally. The default login policy does not provide for checking failed logins.

1. Time frame for consecutive logins in minutes: Observation time interval in minutes. The time interval starts with the first failed login attempt. The value 0 means no time limit, i.e. all consecutive failed logins are counted.

2. Maximum number of consecutive failed logins: Number of failed logins that must occur within the configured time interval for the user to be blocked. The value 0 disables the check.

3. Block type: Defines whether a user blocked due to failed logins is automatically unlocked after a certain time (Timed) or must be unlocked manually by an admin (Manual unlock). A blocked user is displayed as Deactivated in the user overview and is unlocked via Activate. The unlocking user requires administrative access for user management.

4. Block duration in minutes: If automatic unlocking is configured, the duration in minutes can be specified here. The default is 15 minutes.

5. Configuration info: The configuration fields above are related to each other. The configuration is summarized here once again in words to clearly present the configured constellation to the user.

Banner configuration¶

The dialog makes it possible to store a text that is displayed to users at login. By default, no text is preset. The Banner text may be at most 1000 characters long.

Below is an example of a banner displayed in the login dialog.

Default passwords¶

The use of default passwords is not permitted. When starting up the software, you must assign your own password before you can use the system.

When adding a new user, an administrator assigns a password for the new user. This means that the password is known to a third party. The user must assign their own password when logging in for the first time before they can log into the system.

Password security¶

The security of passwords depends on their length and the characters used. Users who have not yet developed a strategy for creating complex passwords may find complex password requirements annoying.

In this case, it is possible to customize the Password policies to suit your own requirements. The customization should meet the security requirements of the application. The default password policy is based on the specifications of the German Federal Office for Information Security.

User Notification for Failed Logins¶

Failed logins can have a variety of reasons, for example:

• The user does not exist (anymore) in the system.

• The password is incorrect.

• The user has been blocked.

From a usability perspective, the user could be told the reason. However, this is ruled out for security reasons, as an attacker could use the information to optimize the attack.

Consequently, regardless of the technical reason for a failed login attempt, the user is always shown the same error message. The error message is Invalid username or password (in German: Ungültiger Benutzername oder Passwort).

Failed login attempts are documented in the event log of the system.

Brute force protection¶

A brute force attack is a method in which an attacker systematically tries all possible combinations of passwords or keys to gain unauthorized access to the system. It is a time-consuming and resource-intensive approach that relies purely on computing power without exploiting vulnerabilities in the target system.

The threat is countered by an exponentially increasing time delay between failed login attempts, so that only a small number of passwords can be checked in a finite amount of time.

After the 𝑛-th failed login attempt, the next login attempt is delayed by 2𝑛−1 seconds, i.e. 1, 2, 4, 8 … seconds. The exponential growth is limited to a maximum of 900 seconds. The delay applies per IP address of the requesting client, regardless of the username used. It therefore also applies to admin users and LDAP users.

The time until the next login attempt is displayed to the user in the login dialog: Too many requests. Please try again in … seconds.